# Tracker Configuration

To start tracking user activity on your website, add the Rybbit tracking script to your site's HTML.

## Installation
The webpage should give you this script tag like this when you first add a website. Place it within the `<head>` section of your website. Include it on every page you wish to track.

```html
<script src="https://app.rybbit.io/api/script.js" async data-site-id="YOUR_SITE_ID"></script>
```

If you are self-hosting Rybbit `app.rybbit.io` will be domain of your Rybbit instance.

## Configuration Options

You can customize the script's behavior using `data-*` attributes on the `<script>` tag:

### `data-track-spa`

Set to `"false"` to disable automatic pageview tracking for single page applications (React, Vue, etc). You will need to manually call `window.rybbit.pageview()` or `window.rybbit.track()` for all but the initial pageview.

-   **Default:** `"true"`
-   **Example:** `data-track-spa="false"`

### `data-track-query`

Set to `"false"` to disable tracking of URL query strings. This enhances privacy by preventing potentially sensitive information in query parameters (such as session tokens, search queries, or UTM parameters) from being stored in your analytics data.

-   **Default:** `"true"`
-   **Example:** `data-track-query="false"`

{/* ### `data-track-outbound`

Set to `"false"` to disable automatic tracking of outbound link clicks. When enabled, the script automatically detects when a user clicks on a link to an external domain and tracks it with an event type of "outbound".

-   **Default:** `"true"`
-   **Example:** `data-track-outbound="false"` */}

### `data-skip-patterns`

A JSON string array of URL path patterns to ignore. Pageviews matching these patterns won't be tracked. Supports two types of wildcards:

- `*` - Matches any characters within a single path segment (doesn't match across `/`)
- `**` - Matches any characters across multiple path segments (includes `/`)

Examples of pattern matching:
- `/admin/*` matches `/admin/dashboard` but not `/admin/users/list`
- `/admin/**` matches both `/admin/dashboard` and `/admin/users/list`
- `/blog/*/comments` matches `/blog/post-123/comments` but not `/blog/category/post/comments`
- `/blog/**/comments` matches any comments page regardless of path depth

-   **Default:** `[]`
-   **Example configuration:**
    ```html
    data-skip-patterns='["/admin/**", "/blog/drafts/*", "/preview/**"]'
    ```

### `data-mask-patterns`

A JSON string array of URL path patterns to mask for privacy. Pageviews matching these patterns will be tracked, but the actual URL path will be replaced with the pattern itself in analytics data.

Supports the same wildcard patterns as `data-skip-patterns`:
- `*` - Single path segment wildcard
- `**` - Multi-segment wildcard

Common use cases:
- Mask user-specific pages: `/users/*/profile` will show as `/users/*/profile` instead of the actual username
- Mask all product pages: `/products/**` will hide specific product paths
- Mask order confirmation pages: `/checkout/*/confirmation` will hide order IDs

-   **Default:** `[]`
-   **Example configuration:**
    ```html
    data-mask-patterns='["/users/*/settings", "/accounts/**", "/orders/*/details"]'
    ```

### `data-debounce`

The delay (in milliseconds) before tracking a pageview after URL changes via the History API (`pushState`, `replaceState`). Set to `0` to disable debouncing.

-   **Default:** `"500"`
-   **Example:** `data-debounce="1000"`


**Example with multiple options:**

```html
<script
  src="https://api.rybbit.io/api/script.js"
  async
  data-site-id="456"
  data-skip-patterns='["/admin/**", "/preview/*"]'
  data-mask-patterns='["/users/*/profile", "/orders/**"]'
  data-track-query="false"
  data-debounce="300"
></script>
```

